home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / bupv100a.zip / CHAPT01.TXT < prev    next >
Text File  |  1991-09-05  |  17KB  |  437 lines
  1.                                                  Chapter 1
  2.                                                  Fast Screen Writing Routines
  3.                                                  The Basner Utilities v1.0a
  4.  
  5.  "Look In, Look The Storm In The Eye. Look Out To The Sea And The Skies.
  6.   Look In, Look Out, Look Around. Tough Times Demand Tough Talk."
  7.                                         Neal Peart - RUSH
  8.  
  9.  
  10.  
  11.  1.1                                             Fast Screen Writing Routines
  12. ------------------------------------------------------------------------------
  13.  
  14. { SPECIAL NOTE: The Basner Utilities are currently in beta test mode, so the
  15.                 documentation may not be complete on all routines. Please
  16.                 refer to the include demo files for any updates to the code. }
  17.  
  18. INTERFACE
  19.  
  20. The basFAST unit contains several objects which themselves contain several
  21. powerful screen writing procedures. The objects are:
  22.  
  23.   SCREENOBJ  : The actual screen writing routines, such as WriteCenter,
  24.                SaveScreen and PartRestoreScreen.
  25.  
  26.   WINDOWOBJ  : Windowing and box routines.
  27.  
  28.  1.2                                             Fast Screen Writing Routines
  29. ------------------------------------------------------------------------------
  30.  
  31. IMPLEMENTATION
  32.  
  33. I..ScreenOBJ - The Fast Screen Writing Methods.
  34.  
  35.   ScreenOBJ
  36.     CONSTRUCTOR Init;
  37.     FUNCTION    ColorAttr( C1, C2 : byte ): byte;
  38.     FUNCTION    ReadByte( X, Y : byte ): longint;
  39.     PROCEDURE   SetColors( C1, C2 : byte );
  40.     PROCEDURE   WriteByte( X, Y, CA : byte; Txt : char );
  41.     PROCEDURE   WriteAt( X, Y, CA : byte; Txt : string );
  42.     PROCEDURE   WritePlain( X, Y : byte; Txt : string );
  43.     PROCEDURE   WriteBack( X, Y, CA : byte; Txt : string );
  44.     PROCEDURE   WriteBetween( X1, X2, Y, CA : byte; Txt : string );
  45.     PROCEDURE   WriteCenter( Y, CA : byte; Txt : string );
  46.     PROCEDURE   WriteVertical( X, Y, CA : byte; Txt : string );
  47.     PROCEDURE   PartClear( X1, Y1, X2, Y2, CA : Byte; Txt : char );
  48.     PROCEDURE   ClearScreen( CA : byte; Txt : char );
  49.     PROCEDURE   PartSaveScreen( X1, Y1, X2, Y2, ScreenField : byte );
  50.     PROCEDURE   SaveScreen( ScreenField : byte );
  51.     PROCEDURE   PartRestoreScreen( X1, Y1, X2, Y2, ScreenField : byte );
  52.     PROCEDURE   RestoreScreen( ScreenField : byte );
  53.     DESTRUCTOR  Done;
  54.   PRIVATE
  55.     VideoSegment : word;
  56.     NormalTxt : byte;
  57.     Highlited : byte;
  58.     WriteDelay : integer;
  59.     ScreenStorage : array [ 1..cMaxSaveScreens ] of bScreenInfo;
  60.  
  61.  
  62.  
  63.  1.3                                             Fast Screen Writing Routines
  64. ------------------------------------------------------------------------------
  65.  
  66. DEFINITIONS AND USAGE
  67.  
  68. 1..Constructor
  69.  
  70.   INIT initializes all private and public variables used within the ScreenOBJ
  71. object and sets up all pointers and field arrays.
  72.  
  73.   EXAMPLE:
  74.  
  75.     Program DEMIO1;
  76.  
  77.     Uses Crt, Dos, basFAST;
  78.  
  79.     begin
  80.       with Screen do begin
  81.         Init; { Initializes the object }
  82.         ClearScreen( ColorAttr( Blue, Black ), '░' );
  83.         WriteCenter( 3, ColorAttr( Yellow, Red ), 'The Basner Utilities v1.0a
  84.                                                    For Turbo Pascal 6.0!' );
  85.       end; { LOOP: Screen }
  86.     end. { PROGRAM: DEMIO1 }
  87.  
  88. 2..Functions
  89.  
  90.   Within the ScreenOBJ object, there are a few useful functions for returning
  91. information from the object's private variables. These include:
  92.  
  93.   ColorAttr( Foreground, Background : byte )
  94.               Combines the passed Foreground And Background attribute bytes
  95.               into a single byte usable by the ScreenOBJ object.
  96.  
  97.     SYNTAX: TempColorByte := ColorAttr( Blue, Red );
  98.             {Sets variable TempColorByte to 20 (bitwise = Blue On Red ).}
  99.  
  100.             WriteAt( 1, 1, ColorAttr( Yellow, Black ), 'This Is A Test!' );
  101.             {Writes the specified string at screen coordinate 1, 1 using
  102.              a Yellow on Black color scheme.}
  103.  
  104.   ReadByte( X, Y : byte )
  105.               Reads a byte from screen memory (at the passed X and Y
  106.               coordinates) and returns it in the form of a long integer.
  107.  
  108.  
  109.  1.4                                             Fast Screen Writing Routines
  110. ------------------------------------------------------------------------------
  111.  
  112.     SYNTAX: ScreenInfo := ReadByte( 1, 1 );
  113.             {Sets the variable ScreenByte to the combined values of the
  114.             character at screen 1, 1.}
  115.  
  116.            ScreenChar := chr( lo( ReadByte( 1, 1 )));
  117.            {Sets the variable ScreenChar to the CHARACTER at screen
  118.            position 1, 1.}
  119.  
  120. 3..Procedures
  121.  
  122.   A..Writing Text To The Screen.
  123.  
  124.   The power of the ScreenOBJ object's procedures is not to be taken lightly.
  125. Within this object are procedures to allocate and deallocate screen memory.
  126. (which, if used incorrectly, could definitely lockup your PC!) But, fear of
  127. program crashes aside, the procedures are very useful and versatile.
  128. Contained within the object are:
  129.  
  130.   SetColors( Normal_Text, Hilited_Text : byte )
  131.               Sets the default colors used by ScreenOBJ.
  132.  
  133.     SYNTAX: SetColors( ColorAttr( Yellow, Black ), ColorAttr( Black, Cyan ));
  134.             {Sets the default normal text color to Yellow on Black and the
  135.             default hilited text color to Black on Cyan.}
  136.  
  137.   WriteByte( X, Y, Color : byte; Txt : char )
  138.               Writes a character directly to screen memory at position X, Y
  139.               using the specified color scheme.
  140.  
  141.     SYNTAX: WriteByte( 1, 1, ColorAttr( White, Blue ), 'A' );
  142.             {Puts 'A' at position 1,1 in screen memory using the specified
  143.             color scheme.}
  144.  
  145.  
  146.  1.5                                             Fast Screen Writing Routines
  147. ------------------------------------------------------------------------------
  148.  
  149.   WriteAt( X, Y, Color : byte; Txt : string )
  150.               Writes a string directly to screen memory starting at position
  151.               X, Y using the specified color scheme.
  152.  
  153.     SYNTAX: WriteAt( 1, 1, ColorAttr( White, Black ), 'THE BASNER UTILITIES' );
  154.             {Writes the specified string at position 1, 1 in screen memory
  155.             using the specified color scheme.}
  156.  
  157. SPECIAL NOTE:
  158.   All descendants of the WriteAt procedure can hilite characters within the
  159. passed string. By placing a ~ to mark the beginning AND then ending of the
  160. hilited text, certain sections of the text may be defined as hilited and will
  161. be printed using the specified hilite color (as per the SetColors procedure).
  162.  
  163. EXAMPLE:
  164.   with Screen do begin
  165.     Init; { Initialize the object }
  166.     SetColors( ColorAttr( Cyan, Black ), ColorAttr( Black, Red ));
  167.     WritePlain( 1, 1, 'The Basner Utilities Are ~EXCELLENT~! );
  168.    end; { LOOP: Screen }
  169.  
  170.   {Initializes the object before use. Sets default colors. Then, prints the
  171.   passed string using default colors. The substring 'EXCELLENT' will be printed
  172.   in the default hilite color scheme of Black on Red.}
  173.  
  174.      WritePlain( X, Y : byte; Txt : string )
  175.               Writes a string directly to screen memory at position X, Y
  176.               using the default color scheme(s).
  177.  
  178.     SYNTAX: WritePlain( 1, 1, 'These Are The ~Default~ Colors...' );
  179.             {Writes the passed text starting at position 1, 1 in screen
  180.             memory using the default normal and hilited text color schemes.}
  181.  
  182.  
  183.  1.6                                             Fast Screen Writing Routines
  184. ------------------------------------------------------------------------------
  185.  
  186.     WriteBack( X, Y, CA : byte; Txt : string )
  187.               Writes text BACKWARD from the end to the beginning of the string,
  188.               so that the first character is at position X, Y, using
  189.               specified color scheme.
  190.  
  191.               NOTE: There is a default pause of 500 milliseconds (.5 seconds)
  192.                     between each character printed.
  193.  
  194.     SYNTAX: WriteBack( 41, 1, ColorAttr( White, Black ), 'The Basner Utils!' );
  195.             {Writes the specified string backwards on the screen.}
  196.  
  197.     WriteBetween( X1, X2, CA : byte; Txt : string )
  198.               Writes a string centered on the screen between positions X1, Y
  199.               and X2, Y using the specified color scheme.
  200.  
  201.     SYNTAX: WriteBetween( 10, 71, 3, ColorAttr( Yellow, Blue ),
  202.                           ' * The Basner Utilities Version 1.0a * ' );
  203.             {Writes the specified string centered between screen coordinates
  204.             10,3 and 71,3 using the specified color scheme.}
  205.  
  206.     WriteCenter( Y, CA : byte; Txt : string )
  207.               Writes a string centered in screen row Y using the specified
  208.               color scheme.
  209.  
  210.     SYNTAX: WriteCenter( 3, ColorAttr( Yellow, Blue ),
  211.                          ' * The Basner Utilities Version 1.0a * ' );
  212.             {Same as the example for WriteBetween, but centers it in row 3
  213.             of the screen's memory using the specified color scheme.}
  214.  
  215.     WriteVertical( X, Y, CA : byte; Txt : string )
  216.               Writes a string vertically on the screen starting at position
  217.               X, Y using the specified color scheme.
  218.  
  219.  
  220.  1.7                                             Fast Screen Writing Routines
  221. ------------------------------------------------------------------------------
  222.  
  223.     SYNTAX: WriteVertical( 1, 1, ColorAttr( LightCyan, Black ),
  224.                            'The Basner Utilities' );
  225.             {EXAMPLE BY DISPLAY}
  226.             T
  227.             h
  228.             e
  229.  
  230.             B
  231.             a
  232.             s
  233.             n
  234.             e
  235.             r
  236.  
  237.             U
  238.             t
  239.             i
  240.             l
  241.             i
  242.             t
  243.             i
  244.             e
  245.             s
  246.  
  247.  
  248.  
  249.  
  250.  1.8                                             Fast Screen Writing Routines
  251. ------------------------------------------------------------------------------
  252.  
  253.     B..Screen Manipulation Routines
  254.  
  255.   There are a few include routines for saving, restoring and manipulating the
  256. physical screen. Please be sure to use the Init constructor to initialize the
  257. pointers, arrays and constants within the object before using these routines.
  258. Include routines are:
  259.  
  260.     PartClear( X1, Y1, X2, Y2, CA : byte; Txt : char )
  261.               Clears part of the screen in a box form and fills the screen with
  262.               the specified character in Txt. The box is shaped using position
  263.               X1, Y1 as the upper-left corner and X2, Y2 as the bottom-right
  264.               corner of the box.
  265.  
  266.     SYNTAX: PartClear( 3, 2, 78, 24, ColorAttr( Blue, Black ), '▓' );
  267.             {Clears a box using the passed coordinates, then filling it with
  268.             '▓' using the specified color scheme.}
  269.  
  270.     ClearScreen( CA : byte; Txt : char )
  271.               Clears the ENTIRE screen and then fills it with the specified
  272.               character in Txt using the passed color scheme (as per
  273.               PartClear).
  274.  
  275.     SYNTAX: ClearScreen( ColorAttr( LightBlue, Black ), 'A' );
  276.             {Clears the entire screen and then fills it with 'A' using the
  277.             specified color scheme.}
  278.  
  279.     PartSaveScreen( X1, Y1, X2, Y2, ScreenField : byte )
  280.               Saves a portion of the screen to a private array within the
  281.               object. The field of the private array is specified by
  282.               ScreenField (min. 1, max. 5 currently).
  283.  
  284.               NOTE: There is currently an object-defined maximum of 5
  285.                     screens that may be saved within the object.
  286.  
  287.     SYNTAX: PartSaveScreen( 1, 1, 40, 25, 1 );
  288.             {Saves the portion of the physical screen from 1,1 to 40,25 into
  289.             field 1 of the private array.}
  290.  
  291.  
  292.  1.9                                             Fast Screen Writing Routines
  293. ------------------------------------------------------------------------------
  294.  
  295.     SaveScreen( ScreenField : byte )
  296.               This procedure works the same as PartSaveScreen, but instead
  297.               saves the ENTIRE screen off into the private array.
  298.  
  299.     SYNTAX: SaveScreen( 3 );
  300.             {Saves the entire screen off into the third field of the private
  301.             array for storage of screens.
  302.  
  303.     PartRestoreScreen( X1, Y1, X2, Y2, ScreenField : byte )
  304.               Partially restores saved information to video memory.
  305.  
  306.               NOTE: Be sure to only restore saved information to the screen's
  307.                     memory, as uninitialized variables and records contain
  308.                     whatever values were in the memory allocated to them prior
  309.                     to its usage as variable storage!
  310.  
  311.     SYNTAX: PartRestoreScreen( 2, 2, 79, 24, 1 );
  312.             {Restore the part of the screen previously stored that was within
  313.             coordinates 2,2 and 79,24 in field 1 of the private storage array.}
  314.  
  315.     RestoreScreen( ScreenField : byte )
  316.               This procedure works the same as PartRestoreScreen, but restores
  317.               ALL information for the saved video screen.
  318.  
  319.     SYNTAX: RestoreScreen( 5 );
  320.             {Restores all screen information stored in array 5 of the
  321.             private storage array to the physical screen.}
  322.  
  323.  
  324.  1.10                                            Fast Screen Writing Routines
  325. ------------------------------------------------------------------------------
  326.  
  327. 4..Destructor
  328.  
  329.   Finally, the destructor for ScreenOBJ, Done, deallocates all allocated
  330. memory that was used for the object's methods and variables.
  331.  
  332.     Done
  333.               Deallocates memory.
  334.  
  335.     SYNTAX: Done;
  336.  
  337.  
  338.  1.11                                            Fast Screen Writing Routines
  339. ------------------------------------------------------------------------------
  340.  
  341. II..WindowOBJ - The Windowing Methods.
  342.  
  343.   WindowOBJ = object
  344.     CONSTRUCTOR Init;
  345.     PROCEDURE   Box( X1, Y1, X2, Y2, CA, BType : byte );
  346.     PROCEDURE   FillBox( X1, Y1, X2, Y2, CA, BType : byte );
  347.     PROCEDURE   ShadowBox( X1, Y1, X2, Y2, CA, BType : byte );
  348.     PROCEDURE   ExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
  349.     PROCEDURE   ShadowExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
  350.     DESTRUCTOR  Done;
  351.   end;
  352.  
  353.  
  354.  1.12                                            Fast Screen Writing Routines
  355. ------------------------------------------------------------------------------
  356.  
  357. DEFINITIONS AND USAGE
  358.  
  359. 1..Constructor
  360.  
  361.     Init
  362.               Allocates memory for the WindowOBJ object's private variables
  363.               and methods. This routine MUST be called in order to properly
  364.               use the object's procedures!
  365.  
  366.     SYNTAX: Init;
  367.  
  368. 2..Procedures
  369.  
  370.   Within the WindowOBJ object, there are several different forms of boxes
  371. (ie, windows) that can be called, ranging from unfilled outlines to exploding,
  372. shadowed boxes. The box types are:
  373.  
  374. ##  Box Type
  375. -------------------------------------------------
  376. 1   No Box Characters
  377. 2   Single Line Box
  378. 3   Double Line Box
  379. 4   Single Line Horizontal, Double Line Vertical
  380. 5   Double Line Horizontal, Single Line Vertical
  381.  
  382. These include:
  383.  
  384.     Box( X1, Y1, X2, Y2, CA, BType : byte )
  385.               Creates only the outline of a window in video memory using the
  386.               specified color scheme. This method does not fill the interior
  387.               of the box.
  388.  
  389.     SYNTAX: Box( 2, 2, 40, 15, ColorAttr( White, Black ), 3 );
  390.             {Draws a double lined box using position 2,2 as the upper-left
  391.             corner and 40,15 as the bottom right corner using the specified
  392.             color scheme.}
  393.  
  394.     FillBox( X1, Y1, X2, Y2, CA, BType : byte );
  395.               Creates a box, as per Box, but fills the interior of the box
  396.               with spaces using the specified color scheme.
  397.  
  398.  
  399.  1.13                                            Fast Screen Writing Routines
  400. ------------------------------------------------------------------------------
  401.  
  402.     SYNTAX: FillBox( 2, 10, 79, 24, ColorAttr( Yellow, Blue ), 1 );
  403.             {Draws a single lined box, like Box, and fills the interior with
  404.             spaces of the specified color scheme.}
  405.  
  406.     ShadowBox( X1, Y1, X2, Y2, CA, BType : byte )
  407.               Similar to FillBox, ShadowBox creates a filled box of type
  408.               BType, and then shades the bottom and right side of the box to
  409.               create a 3dimensional feel to the box. The shading uses the
  410.               characters in screen memory along the "shadowed" edges of the
  411.               box and puts a darkening color scheme to it to create the
  412.               feeling of 3 dimensions.
  413.  
  414.     SYNTAX: ShadowBox( 5, 3, 76, 23, ColorAttr( Yellow, Blue ), 4 );
  415.  
  416.     ExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
  417.               Explodes a filled box from the center of the box's area outward
  418.               to its determined corners using the specified color scheme.
  419.  
  420.     SYNTAX: ExplodeBox( 2, 2, 79, 24, ColorAttr( Black, Red ), 2 );
  421.  
  422.     ShadowExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
  423.               Similar to ExplodeBox, ShadowExplodeBox creates a growing box
  424.               and shades the finished box to create the 3dimensional feel.
  425.  
  426.     SYNTAX: ShadowExplodeBox( 2, 2, 79, 24, ColorAttr( Black, Red ), 2 );
  427.  
  428. 3..Destructor
  429.  
  430.     Done
  431.               Deallocates memory reserved for the WindowOBJ object.
  432.  
  433.     SYNTAX: Done;
  434.  
  435. END. { DOCUMENTATION: Chapter 1 }
  436.  
  437.